home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 14 / CU Amiga Magazine's Super CD-ROM 14 (1997)(EMAP Images)(GB)(Track 1 of 3)[!][issue 1997-09].iso / CUCD / Programming / Mesa-2.2 / src / dd.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-03-13  |  14.5 KB  |  459 lines
  1. /* $Id: dd.h,v 1.4 1997/02/10 19:22:47 brianp Exp $ */
  2.  
  3. /*
  4.  * Mesa 3-D graphics library
  5.  * Version:  2.2
  6.  * Copyright (C) 1995-1997  Brian Paul
  7.  *
  8.  * This library is free software; you can redistribute it and/or
  9.  * modify it under the terms of the GNU Library General Public
  10.  * License as published by the Free Software Foundation; either
  11.  * version 2 of the License, or (at your option) any later version.
  12.  *
  13.  * This library is distributed in the hope that it will be useful,
  14.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16.  * Library General Public License for more details.
  17.  *
  18.  * You should have received a copy of the GNU Library General Public
  19.  * License along with this library; if not, write to the Free
  20.  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  21.  */
  22.  
  23.  
  24. /*
  25.  * $Log: dd.h,v $
  26.  * Revision 1.4  1997/02/10 19:22:47  brianp
  27.  * added device driver Error() function
  28.  *
  29.  * Revision 1.3  1997/01/16 03:34:33  brianp
  30.  * added preliminary texture mapping functions and cleaned up documentation
  31.  *
  32.  * Revision 1.2  1996/11/13 03:51:59  brianp
  33.  * updated comments
  34.  *
  35.  * Revision 1.1  1996/09/13 01:38:16  brianp
  36.  * Initial revision
  37.  *
  38.  */
  39.  
  40.  
  41. #ifndef DD_INCLUDED
  42. #define DD_INCLUDED
  43.  
  44.  
  45. /* THIS FILE ONLY INCLUDED BY types.h !!!!! */
  46.  
  47.  
  48. /*
  49.  *                      Device Driver (DD) interface
  50.  *
  51.  *
  52.  * All device driver functions are accessed through pointers in the
  53.  * dd_function_table struct (defined below) which is stored in the GLcontext
  54.  * struct.  Since the device driver is strictly accessed trough a table of
  55.  * function pointers we can:
  56.  *   1. switch between a number of different device drivers at runtime.
  57.  *   2. use optimized functions dependant on current rendering state or
  58.  *      frame buffer configuration.
  59.  *
  60.  * The function pointers in the dd_function_table struct are divided into
  61.  * two groups:  mandatory and optional.
  62.  * Mandatory functions have to be implemented by every device driver.
  63.  * Optional functions may or may not be implemented by the device driver.
  64.  * The optional functions provide ways to take advantage of special hardware
  65.  * or optimized algorithms.
  66.  *
  67.  * The function pointers in the dd_function_table struct are first
  68.  * initialized in the "MakeCurrent" function.  The "MakeCurrent" function
  69.  * is a little different in each divice driver.  See the X/Mesa, GLX, or
  70.  * OS/Mesa drivers for examples.
  71.  *
  72.  * Later, Mesa may call the dd_function_table's UpdateState() function.
  73.  * This function should initialize the dd_function_table's pointers again.
  74.  * The UpdateState() function is called whenever the core (GL) rendering
  75.  * state is changed in a way which may effect rasterization.  For example,
  76.  * the TriangleFunc() pointer may have to point to different functions
  77.  * depending on whether smooth or flat shading is enabled.
  78.  *
  79.  * Note that the first argument to every device driver function is a
  80.  * GLcontext *.  In turn, the GLcontext->DriverCtx pointer points to
  81.  * the driver-specific context struct.  See the X/Mesa or OS/Mesa interface
  82.  * for an example.
  83.  *
  84.  * For more information about writing a device driver see the ddsample.c
  85.  * file and other device drivers (xmesa[123].c, osmesa.c, etc) for examples.
  86.  *
  87.  *
  88.  * Look below in the dd_function_table struct definition for descriptions
  89.  * of each device driver function.
  90.  * 
  91.  *
  92.  * In the future more function pointers may be added for glReadPixels
  93.  * glCopyPixels, etc.
  94.  *
  95.  *
  96.  * Notes:
  97.  * ------
  98.  *   RGBA = red/green/blue/alpha
  99.  *   CI = color index (color mapped mode)
  100.  *   mono = all pixels have the same color or index
  101.  *
  102.  *   The write_ functions all take an array of mask flags which indicate
  103.  *   whether or not the pixel should be written.  One special case exists
  104.  *   in the write_color_span function: if the mask array is NULL, then
  105.  *   draw all pixels.  This is an optimization used for glDrawPixels().
  106.  *
  107.  * IN ALL CASES:
  108.  *      X coordinates start at 0 at the left and increase to the right
  109.  *      Y coordinates start at 0 at the bottom and increase upward
  110.  *
  111.  */
  112.  
  113.  
  114.  
  115.  
  116.  
  117. /*
  118.  * Device Driver function table.
  119.  */
  120. struct dd_function_table {
  121.  
  122.    /**********************************************************************
  123.     *** Mandatory functions:  these functions must be implemented by   ***
  124.     *** every device driver.                                           ***
  125.     **********************************************************************/
  126.  
  127.    void (*UpdateState)( GLcontext *ctx );
  128.    /*
  129.     * UpdateState() is called whenver Mesa thinks the device driver should
  130.     * update its state and/or the other pointers (such as PointsFunc,
  131.     * LineFunc, or TriangleFunc).
  132.     */
  133.  
  134.    void (*ClearIndex)( GLcontext *ctx, GLuint index );
  135.    /*
  136.     * Called whenever glClearIndex() is called.  Set the index for clearing
  137.     * the color buffer.
  138.     */
  139.  
  140.    void (*ClearColor)( GLcontext *ctx, GLubyte red, GLubyte green,
  141.                                         GLubyte blue, GLubyte alpha );
  142.    /*
  143.     * Called whenever glClearColor() is called.  Set the color for clearing
  144.     * the color buffer.
  145.     */
  146.  
  147.    void (*Clear)( GLcontext *ctx,
  148.                   GLboolean all, GLint x, GLint y, GLint width, GLint height );
  149.    /*
  150.     * Clear the current color buffer.  If 'all' is set the clear the whole
  151.     * buffer, else clear the region defined by (x,y,width,height).
  152.     */
  153.  
  154.    void (*Index)( GLcontext *ctx, GLuint index );
  155.    /*
  156.     * Sets current color index for drawing flat-shaded primitives.
  157.     */
  158.  
  159.    void (*Color)( GLcontext *ctx,
  160.                   GLubyte red, GLubyte green, GLubyte glue, GLubyte alpha );
  161.    /*
  162.     * Sets current color for drawing flat-shaded primitives.
  163.     */
  164.  
  165.    GLboolean (*SetBuffer)( GLcontext *ctx, GLenum mode );
  166.    /*
  167.     * Selects either the front or back color buffer for reading and writing.
  168.     * mode is either GL_FRONT or GL_BACK.
  169.     */
  170.  
  171.    void (*GetBufferSize)( GLcontext *ctx,
  172.                           GLuint *width, GLuint *height );
  173.    /*
  174.     * Returns the width and height of the current color buffer.
  175.     */
  176.  
  177.  
  178.    /***
  179.     *** Functions for writing pixels to the frame buffer:
  180.     ***/
  181.    void (*WriteColorSpan)( GLcontext *ctx,
  182.                            GLuint n, GLint x, GLint y,
  183.                const GLubyte red[], const GLubyte green[],
  184.                const GLubyte blue[], const GLubyte alpha[],
  185.                const GLubyte mask[] );
  186.    /*
  187.     * Write a horizontal run of RGBA pixels.
  188.     */
  189.  
  190.    void (*WriteMonocolorSpan)( GLcontext *ctx,
  191.                                GLuint n, GLint x, GLint y,
  192.                    const GLubyte mask[] );
  193.    /*
  194.     * Write a horizontal run of mono-RGBA pixels.
  195.     */
  196.  
  197.    void (*WriteColorPixels)( GLcontext *ctx,
  198.                              GLuint n, const GLint x[], const GLint y[],
  199.                  const GLubyte red[], const GLubyte green[],
  200.                  const GLubyte blue[], const GLubyte alpha[],
  201.                  const GLubyte mask[] );
  202.    /*
  203.     * Write an array of RGBA pixels at random locations.
  204.     */
  205.  
  206.    void (*WriteMonocolorPixels)( GLcontext *ctx,
  207.                                  GLuint n, const GLint x[], const GLint y[],
  208.                  const GLubyte mask[] );
  209.    /*
  210.     * Write an array of mono-RGBA pixels at random locations.
  211.     */
  212.  
  213.    void (*WriteIndexSpan)( GLcontext *ctx,
  214.                            GLuint n, GLint x, GLint y, const GLuint index[],
  215.                            const GLubyte mask[] );
  216.    /*
  217.     * Write a horizontal run of CI pixels.
  218.     */
  219.  
  220.    void (*WriteMonoindexSpan)( GLcontext *ctx,
  221.                                GLuint n, GLint x, GLint y,
  222.                    const GLubyte mask[] );
  223.    /*
  224.     * Write a horizontal run of mono-CI pixels.
  225.     */
  226.  
  227.    void (*WriteIndexPixels)( GLcontext *ctx,
  228.                              GLuint n, const GLint x[], const GLint y[],
  229.                              const GLuint index[], const GLubyte mask[] );
  230.    /*
  231.     * Write a random array of CI pixels.
  232.     */
  233.  
  234.    void (*WriteMonoindexPixels)( GLcontext *ctx,
  235.                                  GLuint n, const GLint x[], const GLint y[],
  236.                  const GLubyte mask[] );
  237.    /*
  238.     * Write a random array of mono-CI pixels.
  239.     */
  240.  
  241.    /***
  242.     *** Functions to read pixels from frame buffer:
  243.     ***/
  244.    void (*ReadIndexSpan)( GLcontext *ctx,
  245.                           GLuint n, GLint x, GLint y, GLuint index[] );
  246.    /*
  247.     * Read a horizontal run of color index pixels.
  248.     */
  249.  
  250.    void (*ReadColorSpan)( GLcontext *ctx,
  251.                           GLuint n, GLint x, GLint y,
  252.               GLubyte red[], GLubyte green[],
  253.               GLubyte blue[], GLubyte alpha[] );
  254.    /*
  255.     * Read a horizontal run of RGBA pixels.
  256.     */
  257.  
  258.    void (*ReadIndexPixels)( GLcontext *ctx,
  259.                             GLuint n, const GLint x[], const GLint y[],
  260.                 GLuint indx[], const GLubyte mask[] );
  261.    /*
  262.     * Read a random array of CI pixels.
  263.     */
  264.  
  265.    void (*ReadColorPixels)( GLcontext *ctx,
  266.                             GLuint n, const GLint x[], const GLint y[],
  267.                 GLubyte red[], GLubyte green[],
  268.                 GLubyte blue[], GLubyte alpha[],
  269.                             const GLubyte mask[] );
  270.    /*
  271.     * Read a random array of RGBA pixels.
  272.     */
  273.  
  274.  
  275.    /**********************************************************************
  276.     *** Optional functions:  these functions may or may not be         ***
  277.     *** implemented by the device driver.  If the device driver        ***
  278.     *** doesn't implement them it should never touch these pointers    ***
  279.     *** since Mesa will either set them to NULL or point them at a     ***
  280.     *** fall-back function.                                            ***
  281.     **********************************************************************/
  282.  
  283.    void (*Finish)( GLcontext *ctx );
  284.    /*
  285.     * Called whenever glFinish() is called.
  286.     */
  287.  
  288.    void (*Flush)( GLcontext *ctx );
  289.    /*
  290.     * Called whenever glFlush() is called.
  291.     */
  292.  
  293.    GLboolean (*IndexMask)( GLcontext *ctx, GLuint mask );
  294.    /*
  295.     * Implements glIndexMask() if possible, else return GL_FALSE.
  296.     */
  297.  
  298.    GLboolean (*ColorMask)( GLcontext *ctx,
  299.                            GLboolean rmask, GLboolean gmask,
  300.                            GLboolean bmask, GLboolean amask );
  301.    /*
  302.     * Implements glColorMask() if possible, else return GL_FALSE.
  303.     */
  304.  
  305.    GLboolean (*LogicOp)( GLcontext *ctx, GLenum op );
  306.    /*
  307.     * Implements glLogicOp() if possible, else return GL_FALSE.
  308.     */
  309.  
  310.    void (*Dither)( GLcontext *ctx, GLboolean enable );
  311.    /*
  312.     * Enable/disable dithering.
  313.     */
  314.  
  315.    void (*Error)( GLcontext *ctx );
  316.    /*
  317.     * Called whenever an error is generated.  ctx->ErrorValue contains
  318.     * the error value.
  319.     */
  320.  
  321.  
  322.    /***
  323.     *** For supporting hardware Z buffers:
  324.     ***/
  325.  
  326.    void (*AllocDepthBuffer)( GLcontext *ctx );
  327.    /*
  328.     * Called when the depth buffer must be allocated or possibly resized.
  329.     */
  330.  
  331.    void (*ClearDepthBuffer)( GLcontext *ctx );
  332.    /*
  333.     * Clear the depth buffer to depth specified by CC.Depth.Clear value.
  334.     */
  335.  
  336.    GLuint (*DepthTestSpan)( GLcontext *ctx,
  337.                             GLuint n, GLint x, GLint y, const GLdepth z[],
  338.                             GLubyte mask[] );
  339.    void (*DepthTestPixels)( GLcontext *ctx,
  340.                             GLuint n, const GLint x[], const GLint y[],
  341.                             const GLdepth z[], GLubyte mask[] );
  342.    /*
  343.     * Apply the depth buffer test to an span/array of pixels and return
  344.     * an updated pixel mask.  This function is not used when accelerated
  345.     * point, line, polygon functions are used.
  346.     */
  347.  
  348.    void (*ReadDepthSpanFloat)( GLcontext *ctx,
  349.                                GLuint n, GLint x, GLint y, GLfloat depth[]);
  350.    void (*ReadDepthSpanInt)( GLcontext *ctx,
  351.                              GLuint n, GLint x, GLint y, GLdepth depth[] );
  352.    /*
  353.     * Return depth values as integers for glReadPixels.
  354.     * Floats should be returned in the range [0,1].
  355.     * Ints (GLdepth) values should be in the range [0,MAXDEPTH].
  356.     */
  357.  
  358.  
  359.    /***
  360.     *** Accelerated point, line, polygon, glDrawPixels and glBitmap functions:
  361.     ***/
  362.  
  363.    points_func PointsFunc;
  364.    /*
  365.     * Called to draw an array of points.
  366.     */
  367.  
  368.    line_func LineFunc;
  369.    /*
  370.     * Called to draw a line segment.
  371.     */
  372.  
  373.    triangle_func TriangleFunc;
  374.    /* 
  375.     * Called to draw a filled triangle.
  376.     */
  377.  
  378.  
  379.    /***
  380.     *** Misc functions:
  381.     ***/
  382.  
  383.    GLboolean (*DrawPixels)( GLcontext *ctx,
  384.                             GLint x, GLint y, GLsizei width, GLsizei height,
  385.                             GLenum format, GLenum type, GLboolean packed,
  386.                             const GLvoid *pixels );
  387.    /*
  388.     * Called from glDrawPixels().
  389.     */
  390.  
  391.    GLboolean (*Bitmap)( GLcontext *ctx, GLsizei width, GLsizei height,
  392.                         GLfloat xorig, GLfloat yorig,
  393.                         GLfloat xmove, GLfloat ymove,
  394.                         const struct gl_image *bitmap );
  395.    /*
  396.     * Called from glBitmap().
  397.     */
  398.  
  399.    void (*Begin)( GLcontext *ctx, GLenum mode );
  400.    void (*End)( GLcontext *ctx );
  401.    /*
  402.     * These are called whenever glBegin() or glEnd() are called.
  403.     * The device driver may do some sort of window locking/unlocking here.
  404.     */
  405.  
  406.  
  407.    /***
  408.     *** Texture mapping functions:
  409.     ***/
  410.  
  411.    void (*TexEnv)( GLcontext *ctx, GLenum pname, const GLfloat *param );
  412.    /*
  413.     * Called whenever glTexEnv*() is called.
  414.     * Pname will be one of GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.
  415.     * If pname is GL_TEXTURE_ENV_MODE then param will be one
  416.     * of GL_MODULATE, GL_BLEND, GL_DECAL, or GL_REPLACE.
  417.     */
  418.  
  419.    void (*TexImage)( GLcontext *ctx, GLenum target,
  420.                      GLuint texObject, GLint level, GLint internalFormat,
  421.                      const struct gl_texture_image *image );
  422.    /*
  423.     * Called whenever a texture object's image is changed.
  424.     *    texObject is the number of the texture object being changed.
  425.     *    level indicates the mipmap level.
  426.     *    internalFormat is the format in which the texture is to be stored.
  427.     *    image is a pointer to a gl_texture_image struct which contains
  428.     *       the actual image data.
  429.     */
  430.  
  431.    void (*TexParameter)( GLcontext *ctx, GLenum target, GLuint texObject,
  432.                          GLenum pname, const GLfloat *params );
  433.    /*
  434.     * Called whenever glTexParameter*() is called.
  435.     *    target is GL_TEXTURE_1D or GL_TEXTURE_2D
  436.     *    texObject is the texture object to modify
  437.     *    pname is one of GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER,
  438.     *       GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T, or GL_TEXTURE_BORDER_COLOR.
  439.     *    params is dependant on pname.  See man glTexParameter.
  440.     */
  441.  
  442.    void (*BindTexture)( GLcontext *ctx, GLenum target, GLuint texObject );
  443.    /*
  444.     * Called whenever glBindTexture() is called.  This specifies which
  445.     * texture is to be the current one.
  446.     */
  447.  
  448.    void (*DeleteTexture)( GLcontext *ctx, GLuint texObject );
  449.    /*
  450.     * Called when a texture object can be deallocated.
  451.     */
  452.  
  453. };
  454.  
  455.  
  456.  
  457. #endif
  458.  
  459.